Restructure influxdb3 /plugins for step-by-step clarity #5963
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
MeelahMe
changed the title
MeelahMe
changed the title
…g a processing engine plugin section
…xdata/docs-v2 into 5951-restructure-influxdb3-plugins
There was a problem hiding this comment.
Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.
Comments suppressed due to low confidence (2)
content/shared/v3-core-plugins/extended-plugin-api.md:189
- [nitpick] The placeholder 'METHOD' and 'PARAMETERS' may confuse users. Consider either replacing these with concrete examples or adding a clarifying comment that indicates these are placeholders.
influxdb3_local.cache.METHOD(PARAMETERS)
content/shared/v3-core-plugins/extended-plugin-api.md:95
- [nitpick] Ensure that converting a float with no decimal component to an integer and appending '.0' meets the intended behavior and formatting requirements. Verify this behavior remains consistent with all usage scenarios.
self.fields[key] = f"{int(value)}.0" if value % 1 == 0 else str(value)
…xdata/docs-v2 into 5951-restructure-influxdb3-plugins
MeelahMe
changed the title
There was a problem hiding this comment.
Pull Request Overview
This PR restructures the plugins documentation to provide a more step-by-step guide, making it easier for users to understand and work with the plugin API.
- Introduces a comprehensive "extended-plugin-api.md" with detailed usage examples and guidelines.
- Updates enterprise plugins navigation for consistency in naming.
- Adds two extend-plugin markdown files (for enterprise and core) that reference the shared API content.
Reviewed Changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| content/shared/extended-plugin-api.md | New detailed API documentation with usage examples and guidelines for caching and plugin operations. |
| content/influxdb3/enterprise/plugins.md | Minor text update for naming consistency in the menu. |
| content/influxdb3/enterprise/extend-plugin.md | New file to extend plugins using the shared API. |
| content/influxdb3/core/extend-plugin.md | New file to extend plugins using the shared API. |
Comments suppressed due to low confidence (1)
content/shared/extended-plugin-api.md:15
- The in-memory cache sections appear duplicative, with a top-level 'Maintain state with in-memory cache' (lines 10-14) and a separate 'Guidelines for in-memory caching' (lines 15-17). Consider consolidating or clarifying the distinct purposes to avoid confusion.
- [Guidelines for in-memory caching](#guidelines-for-in-memory-caching)
jstirnaman
requested changes
May 6, 2025
jstirnaman
reviewed
May 6, 2025
jstirnaman
requested changes
May 6, 2025
Comment on lines
126
to
134
| - Can receive keyword arguments (as `args`) from _trigger arguments_ | ||
| - Can access the `influxdb3_local` shared API for writing, querying, and managing state | ||
|
|
||
| 1. Create a `.py` file in your plugins directory | ||
| 2. Define a function with one of the following signatures: | ||
| ### Create a custom plugin | ||
|
|
||
| #### For data write events | ||
| When you need custom functionality, you can create your own plugin by doing the following: | ||
|
|
||
| - [Choose your plugin type](#choose-your-plugin-type) | ||
| - [Create your plugin file](#create-your-plugin-file) |
There was a problem hiding this comment.
Suggested change
| - Can receive keyword arguments (as `args`) from _trigger arguments_ | |
| - Can access the `influxdb3_local` shared API for writing, querying, and managing state | |
| 1. Create a `.py` file in your plugins directory | |
| 2. Define a function with one of the following signatures: | |
| ### Create a custom plugin | |
| #### For data write events | |
| When you need custom functionality, you can create your own plugin by doing the following: | |
| - [Choose your plugin type](#choose-your-plugin-type) | |
| - [Create your plugin file](#create-your-plugin-file) | |
| Plugins: | |
| - receive plugin-specific inputs such as written data, call time, or an HTTP request | |
| - receive keyword arguments that you provide in trigger definitions (as `args`) | |
| - can call the `influxdb3_local` API to write data, run queries, and manage state | |
| ### Create a custom plugin | |
| Follow steps to create a plugin that meets your unique requirements. | |
| 1. [Choose your plugin type](#choose-your-plugin-type) | |
| 2. [Create your plugin file](#create-your-plugin-file) | |
| 3. [Next steps](#next-steps) | |
This section is out of place between example and custom plugins. You could also link to the new "extend-plugin" page.
Comment on lines
439
to
450
| influxdb3 create trigger \ | ||
| --trigger-spec "every:1h" \ | ||
| --plugin-filename "threshold_check.py" \ | ||
| --trigger-arguments threshold=90,[email protected] \ | ||
| --database my_database \ | ||
| threshold_monitor | ||
| ``` | ||
|
|
||
| ##### Share data across plugins | ||
| Your plugin accesses these values through the `args` parameter: | ||
|
|
||
| ```python | ||
| # Store in the global namespace | ||
| influxdb3_local.cache.put("config", {"version": "1.0"}, use_global=True) | ||
|
|
||
| # Retrieve from the global namespace | ||
| config = influxdb3_local.cache.get("config", use_global=True) | ||
| def process_scheduled_call(influxdb3_local, call_time, args=None): | ||
| if args and "threshold" in args: |
There was a problem hiding this comment.
If we still need this, move it to the earlier section about trigger arguments.
Co-authored-by: Jason Stirnaman <[email protected]>
Co-authored-by: Jason Stirnaman <[email protected]>
Co-authored-by: Jason Stirnaman <[email protected]>
Co-authored-by: Jason Stirnaman <[email protected]>
Co-authored-by: Jason Stirnaman <[email protected]>
Co-authored-by: Jason Stirnaman <[email protected]>
Co-authored-by: Jason Stirnaman <[email protected]>
Co-authored-by: Jason Stirnaman <[email protected]>
Co-authored-by: Jason Stirnaman <[email protected]>
Co-authored-by: Jason Stirnaman <[email protected]>
Co-authored-by: Jason Stirnaman <[email protected]>
Co-authored-by: Jason Stirnaman <[email protected]>
Co-authored-by: Jason Stirnaman <[email protected]>
Co-authored-by: Jason Stirnaman <[email protected]>
Co-authored-by: Jason Stirnaman <[email protected]>
Co-authored-by: Jason Stirnaman <[email protected]>
Co-authored-by: Jason Stirnaman <[email protected]>
Co-authored-by: Jason Stirnaman <[email protected]>
Co-authored-by: Jason Stirnaman <[email protected]>
Co-authored-by: Jason Stirnaman <[email protected]>
Co-authored-by: Jason Stirnaman <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
**Objective:
To revise the /plugins section to be more structured and step-by-step than it is now. The goal is to make it easier for users to understand how plugins work, how to configure them, and how to build or extend them—especially for those who are new to InfluxDB 3 or plugin-based architectures.
What the feature does and why it’s useful
Once updated, users should be able to:
part of #5857
closes #5951